/* Copyright (c) 2025 Beijing Semidrive Technology Corporation
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/********************************************************************************************************
 *  \file     Mcal_MemLibc.h                                                                                  *
 *  \brief    This file contains interface header for DMA MCAL driver.                                  *
 *                                                                                                      *
 * <table>                                                                                              *
 * <tr><th>Date           <th>Version                                                                   *
 * <tr><td>2025/01/06     <td>1.0.0                                                                     *
 * </table>                                                                                             *
 *******************************************************************************************************/
#ifndef MCAL_MEMLIBC_H
#define MCAL_MEMLIBC_H

#ifdef __cplusplus
extern "C" {
#endif
/********************************************************************************************************
 *                                      Include header files                                            *
 *******************************************************************************************************/
#include "Mcal_Types.h"
/********************************************************************************************************
 *                                  Global Function Declarations                                        *
 *******************************************************************************************************/
/** *****************************************************************************************************
 * \brief This function copy the data from source to destnation.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcal_MemCpy
 *                      (
 *                          void *dst
 *                          const void *src
 *                          uint32 size
 *                      )
 *
 * Service ID[hex]    : 0x00
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Reentrant
 *
 * Parameters (in)    : dst - pointer to destination address
 *                      src - pointer to source address
 *                      size - copy size
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : E_OK: Copy success.
 *                      MCALLIB_E_PARAM_POINTER: Input address is null.
 *                      MCALLIB_E_PARAM_SIZE: Input size is error.
 *
 * Description        : serves as an alternative to the C standard library
 *                      for implementing memory copy functionality.
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcal_MemCpy(void *dst, const void *src, uint32 size);
/** *****************************************************************************************************
 * \brief This function implement memory clear.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcal_MemClr
 *                      (
 *                          void *dst
 *                          uint32 size
 *                      )
 *
 * Service ID[hex]    : 0x01
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Reentrant
 *
 * Parameters (in)    : dst - pointer to destination address
 *                      size - copy size
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : E_OK: Clear success.
 *                      MCALLIB_E_PARAM_POINTER: Input address is null.
 *                      MCALLIB_E_PARAM_SIZE: Input size is error.
 *
 * Description        : serves as an alternative to the C standard library
 *                      for implementing memory clear functionality.
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcal_MemClr(void *dst, uint32 size);
/** *****************************************************************************************************
 * \brief This function implement memory compare.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcal_MemCmp
 *                      (
 *                          const void *mem1
 *                          const void *mem2
 *                          uint32 size
 *                      )
 *
 * Service ID[hex]    : 0x02
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Reentrant
 *
 * Parameters (in)    : mem1 - pointer to a memory block
 *                      mem2 - pointer to a memory block
 *                      size - compare size
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : E_OK: mem1 == mem2.
 *                      MCALLIB_E_PARAM_POINTER: Input address is null.
 *                      MCALLIB_E_PARAM_SIZE: Input size is error.
 *                      MCALLIB_E_MEM_CMP_FAIL: mem1 != mem2.
 *
 * Description        : memcmp is not heavily used in this project, so the char by char comparision is
 *                      acceptable here.
 *
 * \endverbatim
 * Traceability       : SWSR SWSR_LIB_015
 *******************************************************************************************************/
Std_ReturnType Mcal_MemCmp(const void *mem1, const void *mem2, uint32 size);
/** *****************************************************************************************************
 * \brief This function implement memory set.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcal_MemSet
 *                      (
 *                          void *dst
 *                          uint32 val
 *                          uint32 size
 *                      )
 *
 * Service ID[hex]    : 0x03
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Reentrant
 *
 * Parameters (in)    : dst - point to destination of memset
 *                      val - default value to be set
 *                      size - size to be write, unit is in bytes.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : return the length of the address after the data has been written.
 *
 * Description        : The function is used to set a specific value to a given length of a memory block.
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcal_MemSet(void *dst, uint32 val, uint32 size);
/** *****************************************************************************************************
 * \brief This function implement data reversal.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcal_MemRvs
 *                      (
 *                          void *mem
 *                          uint32 size
 *                      )
 *
 * Service ID[hex]    : 0x04
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Reentrant
 *
 * Parameters (in)    : dst - pointer to data need be reverse.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : None
 *
 * Description        : Implementing data reversal functionality one by one.
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcal_MemRvs(void *mem, uint32 size);
#ifdef __cplusplus
}
#endif
#endif /* MCAL_MEMLIBC_H */
/* End of file */
